클로드 코드 완벽 가이드 — 21장 배포하기 딥다이브 학습 노트

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호) | 참고: https://github.com/codefactory-co

21장에서 다루는 내용

• 배포의 개념 — 개발한 서비스를 사용자가 실제로 접근할 수 있도록 서버나 클라우드에 올리는 과정
• Vercel 설정하기 — Vercel 회원가입, GitHub 연동, 프로젝트 임포트
• Vercel 배포하기 — Next.js 프로젝트를 Vercel에 배포하고 환경변수 설정, 재배포까지

전체 흐름도

[테스트 완료된 프로젝트]
         |
         v
+-------------------+     +------------------------+     +---------------------+
| 01 Vercel 가입    |---->| 02 GitHub 레포 임포트   |---->| 03 프레임워크 확인  |
| vercel.com/signup |     | Import Git Repository  |     | Next.js 자동 인식   |
| Hobby 플랜 선택   |     | 프로젝트 선택 + Import |     | Root Directory: ./  |
+-------------------+     +------------------------+     +---------------------+
                                                                   |
                                                                   v
+-------------------+     +------------------------+     +---------------------+
| 06 환경변수 설정  |<----| 05 빌드 완료           |<----| 04 Deploy 실행     |
| Settings →        |     | Continue to Dashboard  |     | 빌드 로그 확인      |
| Environment Vars  |     | 실패 시 Logs 탭 확인   |     | Deploying... 표시   |
| .env 값 입력+Save |     +------------------------+     +---------------------+
+-------------------+
         |
         v
+-------------------+     +------------------------+
| 07 Redeploy       |---->| 08~10 사이트 확인     |
| 환경변수 반영 위해 |     | Overview → Visit      |
| 재배포 실행       |     | 모든 기능 정상 작동    |
+-------------------+     +------------------------+

선수 지식 체크리스트

• [ ] 20장: 테스트(Playwright) — 배포 전 테스트 통과 필수
• [ ] GitHub 기본 사용법 — 레포지토리 생성, 푸시, 브랜치 개념
• [ ] 환경변수(.env) 개념 — API 키 등 민감 정보 관리 방법
• [ ] Next.js 프로젝트 기본 구조 — Supabase 연동 경험

핵심 키워드

21-1 배포란 무엇인가

한 줄 요약

배포란 개발한 서비스를 실제 사용자가 접근할 수 있도록 서버나 클라우드에 올리는 과정이며, 보안/성능/오류 대응을 꼼꼼히 챙겨야 한다.

쉬운 설명 (비유)

배포 = 요리를 완성한 뒤 손님에게 서빙하는 것

요리(개발) → 맛 검증(테스트) → 서빙(배포)

아무리 맛있는 요리도 서빙하지 않으면 손님은 먹을 수 없다.
서빙할 때도 온도, 위생, 그릇 상태를 확인해야 하듯이
배포할 때도 보안, 성능, 오류 대응을 챙겨야 한다.

실무 예제

배포 전 체크리스트:
─────────────────────────────────────────
✅ 보안 설정    → API 키가 코드에 하드코딩 되어 있지 않은가?
                  .env 파일이 .gitignore에 포함되어 있는가?

✅ 성능 최적화  → 이미지 최적화, 불필요한 패키지 제거

✅ 오류 대응    → 에러 페이지(404, 500) 준비
                  로그 모니터링 도구 연동

✅ 테스트 통과  → 20장에서 작성한 Playwright 테스트 전부 통과

❌ 흔한 실수:
   - .env 파일을 GitHub에 올려버림 → API 키 노출
   - 환경변수를 Vercel에 등록하지 않음 → 500 에러
   - 테스트 없이 바로 배포 → 사용자에게 버그 노출

핵심 체크포인트

• 배포 = 개발한 서비스를 사용자가 실제로 사용할 수 있게 올리는 과정
• 단순히 올리는 것이 아니라 보안, 성능, 오류 대응까지 챙겨야 함
• 데이터베이스(Supabase)는 이미 클라우드에 있으므로 그대로 사용
• 웹사이트 배포만 Vercel로 진행

21-2 Vercel 설정하기

한 줄 요약

Vercel은 Next.js를 만든 회사의 배포 플랫폼으로, GitHub 연동과 무료 Hobby 플랜으로 쉽게 프로젝트를 배포할 수 있다.

쉬운 설명 (비유)

Vercel = 요리를 맡기면 자동으로 서빙까지 해주는 식당 매니저

GitHub에 코드를 올리면(요리 완성) → Vercel이 자동으로 빌드하고(포장)
→ 전 세계 사용자에게 서빙(배포)해 준다.

왜 Vercel인가?
- Next.js를 만든 회사 → Next.js와 궁합이 최고
- 무료 Hobby 플랜 → 돈 없어도 시작 가능
- GitHub 연동 → 코드 푸시하면 자동 배포

실무 예제: Vercel 가입 및 프로젝트 생성

Step 1: 회원가입
─────────────────────────────────────────
1. vercel.com/signup 접속
2. Plan Type → "I'm working on personal projects" (Hobby) 선택
3. 이름 입력 → Continue
4. 소셜 로그인 (GitHub 추천) 또는 이메일 가입

Step 2: GitHub 레포지토리 임포트
─────────────────────────────────────────
1. "Import Git Repository" 화면에서 프로젝트 검색
2. 원하는 레포지토리 옆의 [Import] 버튼 클릭

Step 3: 프로젝트 설정 확인
─────────────────────────────────────────
┌─────────────────────────────────────┐
│ New Project                         │
│                                     │
│ Vercel Team: Code Factory Hobby     │
│ Project Name: k-nomad               │
│                                     │
│ Framework Preset: Next.js  ✅        │ ← 보통 자동 인식
│ Root Directory: ./                  │
│                                     │
│ > Build and Output Settings         │
│ > Environment Variables             │ ← 나중에 설정 가능
│                                     │
│            [Deploy]                 │
└─────────────────────────────────────┘

❌ 주의: 프레임워크가 자동 인식되지 않으면 직접 "Next.js" 선택
✅ 팁: Environment Variables는 첫 배포 후에 설정해도 됨

핵심 체크포인트

• Vercel은 Next.js를 만든 회사의 배포 플랫폼으로, Next.js 호환이 매우 좋음
• Hobby 플랜(무료)으로 개인 프로젝트를 충분히 운영 가능
• GitHub/Google/GitLab/Bitbucket 소셜 로그인 지원
• Import Git Repository로 GitHub 레포를 연결하면 자동 배포 환경 구축
• Framework Preset은 보통 Next.js가 자동 인식됨

21-3 Vercel 배포하기

한 줄 요약

Deploy 버튼 클릭으로 빌드를 실행하고, 환경변수 설정 후 Redeploy하면 실제 서비스가 완성된다.

쉬운 설명 (비유)

배포 과정 = 택배 발송과 비슷

1. [Deploy] 클릭 = 택배 접수
   → "Deploying..." 으로 바뀌며 포장(빌드) 시작

2. 빌드 로그 확인 = 택배 추적
   → Build Logs에서 진행 상황 확인
   → 빨간 에러가 보이면 배달 실패!

3. 환경변수 설정 = 수신인 주소 입력
   → 주소(환경변수) 없으면 택배(서비스)가 도착 못 함
   → .env 파일의 KEY=VALUE를 Vercel에 등록

4. Redeploy = 주소 수정 후 재발송
   → 환경변수 변경 시 반드시 재배포 필요

실무 예제: 배포 전체 흐름

Step 4: Deploy 실행
─────────────────────────────────────────
[Deploy] 버튼 클릭 → "Deploying..." 으로 변경
                    → Build Logs 실시간 확인 가능

  Build Logs:
  Progress: resolved 412, reused 0, downloaded...  11s
  → 의존성 설치, 빌드, 최적화 순서로 진행

Step 5: 빌드 결과 확인
─────────────────────────────────────────
✅ 성공 → [Continue to Dashboard] 버튼 클릭
❌ 실패 → Dashboard의 [Logs] 탭에서 에러 확인
          빨간색 에러 로그를 클로드 코드에 복사+붙여넣기로 수정

Step 6: 환경변수 설정
─────────────────────────────────────────
Settings → Environment Variables 이동

  ┌──────────────────────────────────────────────┐
  │ Key                          Value           │
  │ NEXT_PUBLIC_SUPABASE_URL     https://xxx...  │
  │ NEXT_PUBLIC_SUPABASE_ANON_KEY  eyJhb...      │
  └──────────────────────────────────────────────┘

  - .env 또는 .env.local의 모든 키=값 쌍을 입력
  - [Save] 버튼으로 저장
  - Import .env 기능으로 한 번에 임포트도 가능

Step 7: Redeploy (재배포)
─────────────────────────────────────────
  [Save] 후 화면 아래 [Redeploy] 스낵바 표시
  → [Redeploy] 클릭 → 대화창에서 다시 [Redeploy] 확인

  만약 [Redeploy] 버튼이 사라졌다면:
  Deployments → ··· → Create Deployment
  → main 브랜치 선택 → [Create Deployment] 클릭

실무 예제: 배포 후 확인 및 트러블슈팅

Step 9: 사이트 방문
─────────────────────────────────────────
  Overview 탭 → [Visit] 버튼 클릭
  → 배포된 URL: 프로젝트명.vercel.app

Step 10: 기능 확인
─────────────────────────────────────────
  ✅ 모든 페이지 정상 로딩
  ✅ 데이터베이스(Supabase) 연동 확인
  ✅ API 호출 정상 작동
  ✅ 반응형 디자인 확인

흔한 에러와 해결법:
─────────────────────────────────────────
| 증상                        | 원인                  | 해결                       |
|-----------------------------|-----------------------|----------------------------|
| 500 Internal Server Error   | 환경변수 미등록        | Settings → Env Vars 확인   |
| "Your project's URL and     | Supabase URL/Key 오류 | 환경변수 값 재확인          |
|  Key" 에러                  |                       |                            |
| 빌드 실패                   | 코드 에러/의존성 문제  | Logs 탭 → 클로드 코드 수정 |
| 페이지 로딩 안 됨           | 라우팅 설정 오류       | next.config.js 확인        |

핵심 체크포인트

• [Deploy] 클릭 → 빌드 시작 → Build Logs로 진행 상황 확인
• 빌드 실패 시 Logs 탭에서 빨간 에러 확인 → 클로드 코드에 복붙하여 수정
• 환경변수는 Settings → Environment Variables에서 .env 파일의 모든 값을 입력
• 환경변수 변경 후 반드시 Redeploy(재배포) 필요
• Redeploy 시간 초과 시 Deployments → Create Deployment로 수동 배포
• 배포 완료 후 Overview → Visit으로 실제 사이트 확인

연습문제 풀이

Q1: 배포(Deployment)를 가장 올바르게 설명한 것은?

A: 개발한 서비스를 사용자가 실제로 사용할 수 있게 서버나 클라우드에 올리는 과정이다. 단순히 코드를 올리는 것이 아니라 보안 설정, 성능 최적화, 오류 대응까지 포함한다.

Q2: Vercel에서 환경변수를 설정한 뒤 반드시 해야 하는 작업은?

A: Redeploy(재배포)를 해야 한다. 환경변수를 저장만 하면 기존 배포에는 반영되지 않는다. [Save] 후 나타나는 [Redeploy] 스낵바를 클릭하거나, Deployments → Create Deployment로 재배포해야 변경사항이 적용된다.

Q3: Vercel 배포가 실패했을 때 에러 원인을 확인하는 방법은?

A: 대시보드의 [Logs] 탭으로 이동하면 빨간색으로 표시된 에러 로그를 확인할 수 있다. 에러 메시지를 복사하여 클로드 코드에 붙여넣기하면 원인 분석과 수정 방법을 안내받을 수 있다.

Q4: Vercel의 Hobby 플랜을 선택하는 것이 적합한 경우와 부적합한 경우는?

A: 적합한 경우: 개인 프로젝트, 학습용, 프로토타입, 포트폴리오 사이트 등 비상업적 목적. 부적합한 경우: 상업적 프로젝트는 Pro 플랜이 필요하다. Hobby 플랜은 관대한 무료 티어를 제공하므로 초반에는 적극 활용하는 것이 좋다.

부록 A: 용어 사전

부록 B: 핵심 비교표

부록 C: 추천 참고 자료 & 링크